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NOTE 
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System manual pages may be destroyed. 
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HELP 

SOFTWARE INFORMATION BULLETIN 


INTRODUCTION 

This Software Information Bulletin provides important information 
concerning the Help (HELP) Utilities. Please read this bulletin 
carefully before attempting to install or use these utilities. 


The AT&T 3B2 Computer Help (HELP) Utilities is for use by any user, 
but especially novice users, who need more assistance in using the 
UNIX* System commands. The Help Utilities are part of the UNIX 
System V Release 2.0 configuration provided with all 3B2 
Computers. 


SOFTWARE DEPENDENCIES 

The Help Utilities are independent of all optional utilities. 


Trademark of AT&T Bell Laboratories 
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NOTES ON USING UTILITIES 


Administering 'Help’ 

The Help Utilities Administration Utilities are interactive tools used 
by UNIX System administrators and command developers. The 
Administration Utilities enable these users to add, change, or 
remove information in the Help database. Monitoring the use of the 
Help Utilities is also allowed for some users. 


To use the helpadm command of the Help Utilities you must be 
logged in as root, bin, or you must be a member of group bin. 


DOCUMENTATION 

This Software Information Bulletin should be inserted in the 3B2 
Computer Owner/Operator Manual. 


RELEASE FORMAT 

Storage Structure 

The Help Utilities help commands are installed in the /usr directory. 
The Help Utilities helpadm commands are installed in the /etc 
directory. 
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System Requirements 

The minimum equipment configuration required for the use of the 
Help Utilities is 0.5 megabytes of random access memory. 


To install the Help Utilities software, there must be 686 free blocks 
of storage in the usr file system and six free blocks in the root file 
system. Adequate storage space is checked automatically as part of 
the installation process. The installation process installs the utilities 
only if adequate storage space is available. 


The Help Utilities for the 3B2 Computer are distributed on one 
floppy disk. 


Files Delivered 

The Help Utilities are delivered on a single floppy disk. The directory 
structure and files are as follows. 


DIRECTORY 

FILES 

/usr 

help 

glossary locate 


usage 

starter 

/etc 

helpadm 
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UTILITIES INSTALL PROCEDURE 

Use the standard software installation procedure described in the 
3B2 Computer Owner/Operator Manual for the installation of the 
Help Utilities. 


UTILITIES REMOVE PROCEDURE 

Use the standard software remove procedure described in the 3B2 
Computer Owner /Operator Manual for the removal of the Help 
Utilities. 
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Chapter 1 


INTRODUCTION 


GENERAL 

This guide describes command formats (syntax) and use of the Help 
Utilities provided with your AT&T 3B2 Computer. The commands 
and procedures described in this guide are for someone who needs 
assistance in using the UNIX* System. This utilities is an interactive, 
menu-driven facility which provides information on the UNIX System. 
There are four major sections or modules in the Help Utilities. 

These modules will be described in later chapters of this guide. 


* Trademark of AT&T Bell Laboratories 
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FEATURE DESCRIPTION 

The Help Utilities is an optional 3B2 Computer add-on feature. It 
allows you to easily get a variety of information about the UNIX 
Operating System while on the computer. 

Feature highlights include: 

1. Starter Module - general UNIX System information 

2. Glossary Module - definitions of UNIX System terms 

3. Locate Module - function-related commands 

4. Usage Module - how to use some UNIX System commands 

5. System Administration Operation. 


DISPLAY CONVENTIONS 

The following conventions are used to show your terminal input and 
the system output. 


This style of type is used to show system generated 
responses displayed on your screen. 

This style of bold type is used to show inputs 
entered from your keyboard that are displayed on your 
screen . 

These bracket symbols, < > identify inputs from the 
keyboard that are not displayed on your screen, such 
as: <CR> carriage return, CCTRL d> control d, <ESC g> 
escape g, passwords, and tabs. 

This style of italic type is used for notes that 
provide you with additional information. 
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GUIDE ORGANIZATION 

This guide is structured so you can easily find information without 
having to read the entire text. The remainder of this guide is 
organized as follows: 

e Chapter 2, " HELP MENU," describes the help command and 
the top level menu of the Help Utilities. 

® Chapter 3, " STARTER MODULE," describes the starter option 
and its lower level menu screens. 

• Chapter 4, " GLOSSARY MODULE," describes the glossary 
option and its lower level menu screens. 

® Chapter 5, " LOCATE MODULE," describes the locate option 
and its lower level menu screens. 

« Chapter 6, " USAGE MODULE," describes the usage option 
and its lower level menu screens. 

® Chapter 7, "ADMINISTRATION UTILITIES," describes the 
administration commands used to add or modify information 
in the Help Utilities. 

» Appendix, " MANUAL PAGES," contains the Help Utilities UNIX 
System manual pages. 
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Chapter 2 


HELP MENU 


GENERAL 

This chapter describes the help command and the top level menu of 
the Help Utilities. The top level menu is the help menu. There are 
several menus in the modules of the Help Utilities. In these menus 
there may be one or several screens of other menus or information. 
These layers of menus and information screens are connected 
together and branch out like the branches of a tree. 
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HELP UTILITIES TREE 


help 


starter 

glossary 

locate 

usase 

screen 1 

screen 1 

screen 1 

screen 1 

command 

screen 2 

screen 2 

list 

document 



description 

education 



examples 

local 



options 

teach 





SETTING UP YOUR TERMINAL 

There are a few things you might have to do for the Help Utilities to 
work to its full potential with your terminal. Some of the modules 
have screens which are more than one page long. These screens 
have options which allow you to move forward and backward, one 
page at a time. Important information in some screens is also made 
more noticeable by highlighting words or letters. This highlighting 
does not show up on all terminals or on terminals which are defined 
wrong in your .profile. The following information will help you to set 
up your terminal so that it will work as well as it can with the Help 
Utilities. 
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If the TERM variable is not set in your .profile file, the default 
terminal will be a 450 hard-copy terminal. You must set the TERM 
variable if your terminal is not a 450 hard-copy terminal. All of the 
functions of help will not be available if your TERM variable is set 
wrong or not set at all. For instance, the paging back and forth of 
some screens will not be available on some terminals. The paging 
options n and b are available in some of the screens which are more 
than one page long. The help facility also requires that the tabs are 
set on your terminal. If the tabs are not set, the data displayed may 
look like garbage. 


The SCROLL variable may also be set in your .profile according to 
your preference. The default for SCROLL is yes (SCROLL = yes). If 
the SCROLL variable is set to no (SCROLL = no) and then exported, 
the screen will be cleared before printing the next screen of data. If 
you want the screen to scroll, you must set SCROLL = yes and then 
export SCROLL, or you can simply delete the SCROLL variable from 
your .profile. You should also delete the exporting of SCROLL if you 
delete the variable SCROLL. The lines that should be in your .profile 
are shown below: 

SCROLL = yes 
export SCROLL 

or 

SCROLL = no 
export SCROLL 

For more information on setting up your terminal, refer to the User 
Guide. 
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HELP MENU 

The help menu provides an interface to the other modules of the 
Help Utilities. The help menu contains the options used to enter the 
lower level modules. There is only one way to enter the help menu. 
At the shell command level you type help, followed by a carriage 
return. This displays the help menu. The help menu has only one 
screen: help screen 1. This screen contains the possible options you 
may use to enter the lower level modules of the Help Utilities. All of 
these options require only a single character entry followed by a 
carriage return <CR> for the operation you chose to start. 

After entering the Help Utilities, you will be shown a menu of 
options. At the bottom of the screen will be a prompt where you will 
enter your choice of options. The prompt will look like this: 


Enter choice > 


After you enter a module option, the first screen of that module will 
be printed. This screen will contain information you will use to find 
the data you need in a specific module. This data could be the 
description of a command found in the usage description screen. 


Entering the Help Menu 

You may want to try entering the help menu at this time. It would be 
a good idea to get used to using the Help Utilities before you run 
into problems. The help menu entry method is shown below: 

To enter, type: help <CR> 
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The help menu, screen 1 will be displayed on the terminal. Below is 
the help menu screen: 

/ 

help : UNIX 

System On-Line Help 

choices 

description 

s 

starter: general information 

1 

locate: find a command with Keywords 

u 

usage: information about commands 

g 

glossary: definitions of terms 

q 

Quit 

Enter choice > 





Help Menu, Options 

You will be prompted at the bottom of the screen to enter one of 
the options listed in the help menu. To move on to the module 
where the information you want is located, enter the option when 
you are prompted. Don’t forget the carriage return after the option. 
The following options are used to enter the lower level modules from 
the help menu (except for q which exits the Help Utilities). 
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Option Description 

s Enters starter screen 1 

I Enters locate screen 1 

u Enters usage screen 1 

g Enters glossary screen 1 

q Quits and exits to shell. 

Bypassing the Help Menu 

There may be several steps in the process of reaching the 
information for which you are searching. You may skip the step of 
entering the help menu once you become familiar with the lower 
level modules. For example, if you want to enter the starter screen 
1, you can skip the help screen by entering: 

help starter <CR> 

or you can enter: 

starter <CR> 


Illegal Entries 

Error messages are sometimes printed when you enter an unknown 
or illegal character while in any menu of the Help Utilities. The Help 
Utilities is an interactive system and will tell you when you make 
certain mistakes. If an illegal character is entered while in a menu, 
the following error message is printed. 


_ is an invalid choice. Enter a choice shown above. 
Enter choice > 


At this time you may enter a legal choice. 
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LOWER LEVEL MODULES 

There are four lower level modules each with a set of menus with 
options for selecting various other menus or information. The 
information in these modules will be described later. 

Module Menus 

These menus are interactive, which means the computer will prompt 
you with a list of choices when you must make an entry. Then, you 
must decide what to do. If you make a mistake, the computer will 
print an error message and allow you to make another choice. In 
this way, the computer will teach you how to use the Help Utilities. 


Note: The h (help) option of the lower level module screens 
is only available if you enter that module from the help 
menu. 


Module Contents 


e Starter Module - contains general information on the UNIX 
System and information for beginners. 

« Glossary Module - contains a list of terms and symbols and the 
definitions of those terms and symbols. 

• Locate Module - is a means of identifying UNIX System 
commands by their function. 

• Usage Module - contains information about specific UNIX System 
commands with descriptions, options, and examples 
demonstrating some typical uses. 
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Chapter 3 


STARTER MODULE 


GENERAL 

This chapter describes the starter module and its lower level 
screens. These screens contain general information for beginners. 
There are six screens in the starter module, each with its own 
options. All of these options require only a single character entry 
followed by a carriage return for the operation to start. 
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STARTER MODULE SCREENS 

The starter module contains the following: 


• Command screen - lists some of the basic commands and terms 
for a beginner to learn. 

• Document screen - is a list of important basic UNIX System 
documents. 

• Education screen - is a list of training centers for UNIX System 
courses, including addresses. 

• Local screen - list the name, location, and telephone number of 
your local system administrator. 

® Teach screen - list information about available on-line teaching 
aids. 


Entering Starter Screen 1 

The starter screen 1 can be entered from the help menu as 
explained in Chapter 2. You can also enter the starter screen 
directly from the shell command level. Whether you enter directly 
from the shell or from the help menu you will be put in starter 
screen 1. From there you can choose an option for one of the other 
starter screens. Each screen of the starter module can be entered 
from the starter screen 1 by using the appropriate option. 


The starter screen 1 menu entry methods are shown below: 


To enter, type: help <CR> then enter option s <CR> 
or type: help starter <CR> 
or type: starter <CR> 
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Starter Screen 1 Options 

The options of the starter screen 1 menu are shown below: 


Options 

Description 

h (help) 

Returns to help screen 1 

q (quit) 

Quits and exits to shell 

c (command) 

Displays command screen 

d (document) 

Displays document screen 

e (education) 

Displays education screen 

1 (local) 

Displays local screen 

t (teach) 

Displays teach screen. 


Entering Starter Command Screen 

The starter command screen is entered from starter screen 1. 
starter command screen menu entry method is shown below: 

To enter, type: c <CR> 


The 
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Starter Command Screen Options 

The options of the starter command menu are shown below: 

Options Descriptions 

h (help) Returns to help screen 1 

q (quit) Quits and exits to shell 

s (starter) Returns to starter screen 1. 

Below is an example of the starter command screen: 

Commands & Terms to learn first 

The most basic UNIX system commands and terms are listed here. 

New system users should master these commands and understand the 
meaning of these technical terms before going on to anything else. 



Command 


Technical Terms 

cat 

ed 

mv 

command 

password 

cd 

grep 

pwd 

directory 

pathname 

chmod 

Is 

rm 

file 

program 

cp 

mail 

who 

file system 

shell 

date 

mkdi r 


login 

UNIX system 

for command information 


for definitions: 

1 . enter : 

: q to quit 


1. enter: q to 

quit 

2. type: 

usage cmd name 

, 

2. type: glossary tech term 


where cmd_name = a command name | where tech_term=a term from the list 

Choices: s (restart starter), h (restart help), q (quit) 

Enter choice > 


You can use the commands and terms in this screen to get familiar 
with using the Help Utilities and learn the commands and terms at 
the same time. 
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Entering Starter Documents Screen 

The starter documents screen is entered from starter screen 1. The 
starter documents screen menu entry method is shown below: 

To enter, type: d <CR> 

Starter Documents Screen Options 

The options of the starter documents menu are shown below: 


Options 

h (help) 
q (quit) 
s (starter) 


Description 

Returns to help screen 1 
Quits and exits to shell 
Returns to starter screen 1. 


The following is an example of a few of the documents listed in the 
documents screen: 


— Basics for UNIX System Users 

— Using the File System 

— Screen Editor (vi) Tutorial 

— Shell Tutorial 

— File System Hierarchy/Pathnames 

— Text Formatters Reference. 


Entering Starter Education Screen 

The starter education screen is entered from starter screen 1. The 
starter education screen menu entry method is shown below: 

To enter, type: e <CR> 
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Starter Education Screen Options 

The options of the starter education menu are shown below: 


Options 

h (help) 
q (quit) 
s (starter) 


Description 

Returns to help screen 1 
Quits and exits to shell 
Returns to starter screen 1. 


The following is an example of how information about a training 
center is listed in the education screen. 


Name: 

Location: 

Information: 

Audience: 


AT&T Technologies Dublin Training Center 

Dublin OH 

Call: 800-TRAINER 

AT&T personnel and commercial customers 


Entering Starter Local Screen 

The starter local screen is entered from starter screen 1. The 
starter local screen menu entry method is shown below: 

To enter, type: 1 <CR> 
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Starter Local Screen Options 

The options of the starter local menu are shown below: 


Options 

h (help) 
q (quit) 
s (starter) 


Description 

Returns to help screen 1 
Quits and exits to shell 
Returns to starter screen 1. 


Below is an example of the type of information found in the local 
screen: 


Local System Information: 

The following is an example of information for your system 
that is to be supplied by your system administrator. 

SYSTEM ADMINISTRATOR: Chip Logic 
PHONE NUMBER: 555-8669 
SYSTEM NAME: 3B2 
PROCESSOR TYPE: WE3200 


Choices: s (restart starter), h (restart help), q (quit) 


Enter choice > 
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Entering Starter Teach Screen 

The starter teach screen is entered from starter screen 1. The 
starter teach screen menu entry method is shown below: 

To enter, type: t <CR> 

Starter Teach Screen Options 

The options of the starter teach menu are shown below: 


Options 

h (help) 
q (quit) 
s (starter) 


Description 

Returns to help screen 1 
Quits and exits to shell 
Returns to starter screen 1. 
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Below is an example of the teach screen: 

Teaching Aids Available On-Line 

Name: UNIX Instructional Workbench 

Description: Programs for computer-aided instruction. 

Courses: 1. Fundamentals of the UNIX System 

2. Advanced Use of the UNIX Text Editor 

3. UNIX System Memorandum Macros 

4. Table Processing (tbl) Using the UNIX System 

Ordering: Order UNIX Instructional Workbench through your 

AT&T Technologies Regional Representative (AT&T 
affiliates) or by contacting AT&T Technologies 
Licensing at (919) 697-6930 (commercial customers). 

Choices: s(restart starter), q(quit), h(help) 
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Chapter 4 


GLOSSARY MODULE 


GENERAL 

This chapter describes the glossary module and its lower level 
screens. There are two screens of the glossary module, each with 
its own options. Most of these options require only a single 
character entry followed by a carriage return for the operation to 
start. The option UNIX term is the only exception. 


GLOSSARY MODULE SCREENS 

The glossary module contains the following: 

© Glossary screen 1 - A list of UNIX terms that are defined in 
glossary screen 2 

• Glossary screen 2 - The definition of the terms listed in glossary 
screen 1. 
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Entering Glossary Screen 1 (Terms) 

The glossary screen 1 can be entered from the help menu as 
explained in Chapter 2. You can also enter the glossary screen 
directly from the shell command level. If you enter from the shell, 
you can go directly to glossary screen 2 by entering a UNIX term as 
the last argument on the command line. If you leave off the UNIX 
term argument you will be put in glossary screen 1. From there you 
can choose an option for one of the other glossary screens. 


UNIX term can be a word or phrase special to the UNIX System (file, 
shell, link, or mode). The term is entered at the bottom of glossary 
screen 1; then, glossary screen 2 is automatically entered, and the 
definition is printed on the screen. 


The glossary screen 1 menu entry methods are shown below: 

To enter, type: help <CR> then enter option g <CR> 
or type: help glossary <CR> 
or type: glossary <CR> 
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Glossary Screen 1 Options 

The options of the glossary screen 1 menu are shown below: 


Option 

Description 

h (help) 

Returns to help screen 1 

(if you entered from the help menu) 

q (quit) 

Quits and exits to shell 

n (next) 

Goes to next page 

b (back) 

Goes back one page 

UNIX term 

Goes to glossary screen 2 and displays definition 
of the UNIX term entered. 


Below are a few of the terms listed in glossary screen 1: 


# 

$ 

* 

& 

HOME 

UNIX 

block 

command line 

field 

file 

group 

link 

login 

mode 

owner 

pathname 

pipe 

prompt 

root 

root directory 

shell 

string 

user ID 

white space 
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Entering Glossary Screen 2 (Definitions) 

The glossary screen 2 menu entry methods are shown below: 

To enter, type: help glossary UNIX term <CR> 
or type: glossary UNIX term <CR> 
or type: UNIX term <CR> (from glossary screen 1) 

Glossary Screen 2 Options 

The options of the glossary screen 2 menu are shown below: 


Option 

Description 

h (help) 

Returns to help screen 1 (if you entered from the 
help menu) 

q (quit) 

Quits and exits to shell 

g (glossary) 

Returns to glossary screen 1. 

n (next) 

Goes to next page 

b (back) 

Goes back one page. 
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Below is an example of one of the descriptions found in glossary 
screen 2. The definition shown is for the terms root or root 
directory. 


root : root directory 

The root directory is the base of the tree structure of the 
file system of a UNIX system. It is represented as a slash 
(/) at the beginning of every "full pathname"*. 


* defined in the glossary 


Choices: UNIX_term (from list), g (restart glossary) q (quit) 


Enter choice > 
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Chapter 5 


LOCATE MODULE 


GENERAL 

This chapter describes the locate module and its lower level screens. 
There are two screens in the locate module, each with its own 
options. All of these options require only a single-character entry 
followed by a carriage return for the operation to start. 


LOCATE MODULE SCREENS 

The locate module contains the following: 


• Locate screen 1 - A description of locate, and a list of related 
commands for each key word with a short example of how the 
function- related keywords are used 

© Locate screen 2 - A description of related commands. 


A keyword is a word (not a command) that is related to a group of 
commands through its function. Print is a word which can be 
related by function to such commands as: pr, Is, or cat. So, if you 
need to know which command will perform a function (such as: hunt 
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for an item), you enter that word (hunt). All of the commands that 
perform a similar or related function to hunt will be listed on the 
screen. You can then choose the command that will best suit your 
needs. If you need more information on hunt or other commands, 
you may enter the usage screen or reference the 3B2 Computer 
User Reference Manual. 


Entering Locate Screen 1 

The locate screen 1 menu entry methods are shown below: 

To enter, type: help <CR> then enter option 1 <CR> 
or type: help locate <CR> 
or type: locate <CR> 


Locate Screen 1 Options 

The options of the locate screen 1 menu are shown below: 


Options 

h (help) 
q (quit) 
k ( keyword ) 


Descriptions 

Returns to help screen 1 
Quits and exits to shell 

Goes to locate screen 2 (Enter keyword(s) after 
new prompt). 


Entering Locate Screen 2 

The locate screen 2 menu entry methods are shown below: 


To enter, type: help locate keyword(s) <CR> 
or type: locate keyword(s) <CR> 
or type: k <CR> (from locate screen 1) 
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Locate Screen 2 Options 

The options of the locate screen 2 menu are shown below: 


Options Descriptions 

h (help) Returns to help screen 1 


q (quit) Quits and exits to shell 

k ( keyword) Enter keyword(s) after new prompt (displays 

commands found using the keyword entered) 

c (command) Enter command name, then enter option [d, e, o] 
(links to usage screens) 
d displays the usage description screen 
e displays the usage examples screen 
o displays the usage option screen 


n (next) Goes to next page (on some terminals) 


b (back) Goes back one page (on some terminals). 


Note: The c option goes to the Usage Module and the 
appropriate screen. 
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LOCATE EXAMPLE 

Below is an example of the locate screen: 


locate: Find UNIX System Commands with keywords 


Give locate a list of 1 or more keywords related to the work 
you want to do. It will print a list of UNIX System 
commands whose actions are related to the keywords. For 
example, the keyword list: 

print file could produce the list: The cat (concatenate) command 

The Is (list) command 
The pr (print) command 

To use locate, enter a k. When the "Enter keywords" prompt 
appears, enter the keywords on 1 line, separated by blank 
spaces . 

choices description 

k Enter a list of keywords 

q Quit 

Enter choice > 


If you enter a k as the choice above, the following prompt will be 
displayed. 


Enter keyword(s) > 
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If you enter print as the keyword at the keyword prompt in 
locate screen 1, the following would be displayed in locate 
screen 2. 


r 


The cat (concatenate) command 
The echo command 
The Is (list) command 
The pr (print) command 

The pwd (print working directory) command 
The tail command 


Choices: c (cmd info), k (new keywords), q (quit) 


Enter choice > 
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USAGE MODULE 


GENERAL 

This chapter describes the usage module and its lower level 
screens. There are five screens in the usage module, each with its 
own options. All of these options require only a single-character 
entry followed by a carriage return for the operation to start. 
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USAGE MODULE SCREENS 

The usage module contains the following: 


© Usage Screen 1 - A menu of the possible options 

© Usage Command List Screen - A list of all UNIX System 
commands supported by the Help Utilities 

© Usage Command Description Screen - A description of the 
commands listed in the command list screen 

© Usage Command Examples Screen - Examples of how to use 

each of the commands listed 

• Usage Command Options Screen - All the available options for 
each of the commands listed. 


Entering Usage Screen 1 

The usage module is used to get information on specific commands. 
Once you enter usage screen 1, you may print out a list of 
supported commands or get information on a specific command. To 
get information on a command, just choose option c and enter the 
command after the second prompt. You must then choose what 
type of information you want. You can get a description, an 
example, or possible options of the command. After you enter this 
choice, you will be allowed to make one of several choices. 


The usage screen 1 menu entry methods are shown below: 


To enter, type: help <CR> then enter option u <CR> 
or type: help usage <CR> 
or type: usage <CR> 
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Usage Screen 1 Options 

The options of the usage screen 1 menu are shown below: 

Options Description 

h (help) Returns to help screen 1 

q (quit) Quits and exits to shell 

p (print) Prints usage list screen command list 

c (command) Enter command name, then enter option [d, e, o] 
d displays the description screen 
e displays the examples screen 
o displays the option screen. 

Entering Usage List Screen 

The usage list screen menu entry method is shown below: 

To enter, type: p <CR> (at usage screen 1) 
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Usage List Screen Options 

The options of the usage list screen 1 menu are shown below: 


Options Description 

h (help) Returns to help screen 1 

q (quit) Quits and exits to shell 

c (command) Enter command name, then enter option [d, e, o] 

d displays the description screen 
e displays the examples screen 
o displays the option screen. 

Entering Usage Description Screen 

The usage description screen menu entry methods are shown below: 

To enter, type: help usage command name <CR> 
or type: usage command name <CR> 
or type: d <CR> from usage examples screen 
or type: d <CR> from usage options screen 


You may also enter the description screen from other screens. 

After entering c as the choice in the appropriate screen, you must 
enter a command name. You may then enter the description 
screen by choosing the d option when you are asked to enter a 
choice. The following methods show how to enter from each of the 
other screens. 

To enter, type: d <CR> from usage screen 1 
or type: d <CR> from usage list screen 
or type: d <CR> from locate screen 2 
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Usage Description Screen Options 

The options of the usage description screen menu are shown below: 


Options 

h (help) 
q (quit) 

P (print) 
c (command) 

e (example) 

0 (option) 

1 (locate) 


Description 

Returns to help screen 1 
Quits and exits to shell 
Prints usage list screen 

Enter command name , then enter option [e, o] 
e displays the examples screen 
o displays the option screen 

Displays example screen 

Displays option screen 

Returns to the locate command list (if you 
entered usage from the locate module). 


Entering Usage Example Screen 

The usage example screen menu entry methods are shown below: 


To enter, type: help usage -e command name <CR> 
or type: usage -e command name <CR> 
or type: e <CR> from usage description screen 
or type: e <CR> from usage options screen 
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You may also enter the example screen from other screens. After 
entering c as the choice in the appropriate screen, you must enter a 
command name. You may then enter the example screen by 
choosing the e option when you are asked to enter a choice. The 
following methods show how to enter from each of the other 
screens. 


To enter, type: e <CR> from usage screen 1 
or type: e <CR> from usage list screen 
or type: e <CR> from locate screen 2 

Usage Example Screen Options 

The options of the usage example screen menu are shown below: 


Options 

h (help) 
q (quit) 
p (print) 
c (command) 

d (description) 

0 (option) 

1 (locate) 


Description 

Returns to help screen 1 
Quits and exits to shell 
Prints usage list screen 

Enter command name, then enter option [d, o] 
d displays the description screen 
o displays the option screen 

Displays description screen 

Displays option screen 

Returns to the locate command list (if you 
entered usage from the locate module). 
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Entering Usage Options Screen 

The usage options screen menu entry methods are shown below: 


To enter, type: help usage -o command name <CR> 
or type: usage -o command name <CR> 
or type: o <CR> from description screen 
or type: o <CR> from example screen 


You may also enter the options screen from other screens. After 
entering c as the choice in the appropriate screen, you must enter a 
command name. You may then enter the options screen by 
choosing the o option when you are asked to enter a choice. The 
following methods show how to enter from each of the other 
screens. 


To enter, type: o <CR> from usage screen 1 
or type: o <CR> from usage list screen 
or type: o <CR> from locate screen 2 
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Osage Options Screen Options 

The options of the usage options screen menu are shown below: 


Options 

Description 

h (help) 

Returns to help screen 1 

q (quit) 

Quits and exits to shell 

P (print) 

Prints usage list screen 

c (command) 

Enter command name, then enter option [d, e] 
d displays the description screen 
e displays the examples screen 

d (description) 

Displays description screen 

e (example) 

Displays example screen 

! (locate) 

Returns to locate command list (if you entered 
usage from the locate module) 

n (next) 

Goes to next page 

b (back) 

Goes back one page. 
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USAGE MODULE EXAMPLES 

The following examples may not be an exact copy of the data 
contained in your help database. Due to the fact that the local 
administrator may add, change, or delete information in the 
database, the content of individual screens may be different than 
what is shown here. 


Usage Screen 1 Example 

Below is an example of usage screen 1 


usage: Information about Commands 

usage provides information about specific UNIX System commands. 
Enter one of the choices below to proceed. 

choices Description 

c Obtain usage information for a command 

p Print a list of commands 

q Quit 

Enter choice > _ 
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Usage Lis* Screen Example 

The following is an example of the usage 3ist screen 


usage: Information about Commands 

The following commands are currently included in help: 


cat 

cd 

chmod 

cp 

cut 

date 

echo 

egrep 

f grep 

file 

find 

glossary 

grep 

help 

In 

locate 

Is 

mail 

mesg 

mkdir 

mv 

news 

P r 

ps 

pwd 

rm 

sleep 

sort 

starter 

stty 

tabs 

tai 1 

tee 

time 

touch 

tty 

uname 

usage 

wall 

wc 

who 

write 


Choices: c (enter cmd), q (quit) 


Enter choice > 


If you enter a c as the choice above, the following prompt will be 
displayed. 


Enter command name > 
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After you enter a command name (cmcLname) at the prompt above, 
the following prompt will be displayed. 


Enter d (description), e (examples), or o (options) > 


After entering an option at the prompt above, the chosen screen will 
be displayed. 

Usage Description Screen Example 

Below is an example of the usage description screen for the cat 
command: 


cat 

Syntax Summary: cat [-u] [-s] [-v [-t] [-e] ] file_name ... 
where : 

file_names are simple file names, relative 
pathnames, or full pathnames. 

Description : 

cat is shorthand for "concatenate" . It prints the 
contents of the file[s] specified as its argument[s]. 
If more than one file is specified, cat will print 
each one in sequence on the standard output. 

See also: cp(l), pg(l), pr(l). 


Choices: o(options), e(examples), c(enter cmd), p(print list), 

q ( quit ) 


Enter choice > 


You may now enter a choice, and the appropriate screen will be 
displayed (unless you enter a q). 
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Usage Examples Screen Example 

If you enter an e as the option at the prompt in the cat description 
screen, the following cat examples screen will be displayed. 


cat : Examples 

cat textfile 

--> Prints, on the standard output, the contents of the 
file textfile in the current working directory. 

cat /etc/passwd /etc/group > groupfile 
--> Prints the contents of /etc/passwd and then the contents 

of /etc/group and redirects the output to the file groupfile. 

cat /usr/src/cmd/* ! grep stdio.h 
--> Prints the lines that contain the pattern stdio.h from 
the files in the directory /usr/src/cmd. 


Choices: o(options), d(descr iption) , c(enter cmd), p(print list), 

q(quit) 


Enter choice > 
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Usage Options Screen Example 

If you enter an o as the option at the prompt in the cat examples 
screen, the following cat options screen will be displayed. 

cat : Options 

-u output is not placed in temporary storage before 

printing (unbuffered) 

-s suppresses messages about non-existent files 

-v causes non-printed characters to be printed (except tabs, 

newlines and form-feeds) (e.g. ~G is printed for the bell 
character) 

-t causes tabs to be printed as ~I (used only with -v) 

-e causes a $ character to be printed at the end of 

each line (used only with -v) 


Choices: e(examples), d(description) , c(enter cmd), p(print list), 

q(quit) 


Enter choice > 
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ADMINISTRATION 

UTILITIES 


GENERAL 

The Help Administration Utilities are interactive tools used by UNIX 
System administrators. The Administration Utilities enable 
administrators to add, change, or delete information in the Help 
database. The ability to monitor the use of the Help Utilities is also 
allowed for users with root or bin as a login. 


Entering the 'helpadm’ Menu 

To use the helpadm command and change help data, you must be 
logged in as root, bin, or you must be a member of the group bin 
login. If anyone else tries to change help data, an error message is 
printed at their terminal, and they will be returned to the shell from 
which they entered the Helpadm utilities. The helpadm menu of 
options can be displayed by doing the following: 

To enter, type: helpadm <CR> 
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’helpadm’ Menu 

The options of the helpadm menu are listed below: 


Options Description 

1 To make changes to data in the starter module (only 
root logins may change starter data) 

2 To make changes to data in the glossary module 
(only root or bin logins may change starter data) 

3 To make changes to description, examples, options, 
and keyword data of the locate and usage modules 
(only root or bin logins may change starter data) 

4 To stop monitoring the use of help 
(may be set by root or bin logins only) 

5 To start monitoring the use of help 
(may be set by root or bin logins only) 

q Quits and exits helpadm menu, and returns you to 

the shell command level. 


After entering the helpadm menu and selecting an option, you will 
be allowed to make the chosen action. The possible actions allowed 
in each menu and how to make those actions are described next. 
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CHANGING THE HELP DATABASE 

There are three areas which you may enter in order to make 
changes to the database. The three areas are: 

© Starter 
• Glossary 

« Command information. 


Only one person may change data in any one area at a time. If 
more than one person tries to change data in an area, a message is 
printed at the second or later person’s terminal and they will be 
returned to the shell. If this happens, you should try to make your 
changes at another time. 


Note: The default editor for editing the help database is the 
ed editor. 


Changing Starter Information 

After you enter the starter database, a menu of the starter screens 
is displayed at your terminal. A prompt is printed at the bottom of 
the screen requesting you to enter your choice of screens. After 
you respond, you are placed in the editor specified by the EDITOR 
shell variable in your .profile. The default editor is ed. However, 
you may change the editor that you default to by defining the 
EDITOR shell variable in your .profile and then exporting it. You 
must be logged in as root to change information in the starter 
database. 


Exiting the Editor 

When you have finished editing the data in a screen, you will be 
asked if you are satisfied with the screen you have changed. If you 
are not satisfied, you can re-edit the screen. When you have 
responded that you are satisfied with the screen, you are asked if 
you want the changes entered into the database. To have the 
changes entered, you must respond by typing y for yes. If you do 
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not type y, the database remains unchanged. This prompting 
sequence is used for most of the screens when exiting the edit 
mode. 

Example of Changing Starter Data 

The following is an example of how to change data in the starter 
database. To begin, enter: 

helpadm <CR> 


After entering helpadm, the first helpadm menu will be displayed. 
The helpadm menu is shown below: 


helpadm: UNIX System On-Line help Administrative Utilities 

These software tools will enable the administrator to change 
information in the help facility’s database, and to monitor 
use of the help facility. 


choices 

1 

2 

3 

4 

5 

q 


description 

starter 

glossary 

commands 

prevent recording use of help facility 

record use of the help facility 

quit 


Enter choice > 
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If you enter 1 (starter) as the choice in the helpadm menu, the 
following starter menu will be displayed: 


helpadm: starter 

Which screens of starter do you want to make changes to? 


choices 

c 

d 

e 

1 

t 

q 


description 
commands screen 
documents screen 
education screen 
local screen 
teach screen 
quit 


Enter choice > 


If you do not have permission to change starter information, the 
following message will be displayed; and you will be placed back in 
the shell from which you entered helpadm. Remember, only root 
can make changes to the starter database. 


You do not have permission to change this starter screen. 
Exiting with no changes to the help facility database. 
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Changing Glossary Information 

After you enter the glossary database, you will be prompted for the 
term to be added, changed, or deleted. After you enter the option, 
you will be asked for the term which you are going to add, change, 
or delete. Once you enter the term, you will be placed into the 
default editor to edit the term. When you have finished editing, you 
can exit the editing process by using the procedure explained in the 
" Exiting the Editor” section of this manual. 


Note: If the screen being edited is more than 17 lines, you 
will be put back into the editor in order to shorten the 
definition. 


Adding a Term 

If you wish to add a term to the glossary, you should choose the 
add option when prompted for the option. When you enter a 
glossary term that is not already in the glossary, you will be 
prompted with a message that states the entered term is a new 
term, and assumes you are adding the term. At this point you will 
be placed in the editor specified by the EDITOR shell variable. You 
may then add the definition of the chosen term. The definition 
cannot be more than 17 lines long. When you have finished editing, 
you can exit the editing process by using the procedure explained in 
the ” Exiting The Editor” section of this manual. 


Note: You may only change or delete glossary definitions if 
you have write permission for the definition file. If you do 
not have write permission for the definition file, an error 
message is printed at your terminal, and you will be returned 
to the shell. 


Changing a Term 

To change an existing term, you must enter the term when 
prompted for it. Once you enter an existing term, you will be 
prompted to choose between modifying or deleting the term. If you 
wish to change the term, you should choose the modify option. 

After you enter the option, you will be placed into the default editor 
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specified by the EDITOR shell variable. You may then make your 
changes to the definition of the chosen term. When you have 
finished editing, you can exit the editing process by using the 
procedure explained in the " Exiting the Editor" section of this 
manual. The terms definition cannot be more than 17 lines long. 


Deleting a Term 

To delete an existing term, you must enter the term when prompted 
for it. Once you enter an existing term, you will be prompted to 
choose between modifying or deleting the term. To delete the term, 
you should choose the delete option. If you choose the delete 
option, you will be asked again if you want to delete the term. For 
the term to be deleted, you must respond by typing y for yes. If you 
do not type y, the database remains unchanged. The following is an 
example of deleting a term after you have entered the glossary 
database from the helpadm menu. 


Enter the name of the glossary term to be added/modified/deleted > list 
list is already included in the glossary. 

Do you want to m(modify) its definition or d(delete) it from the glossary? 
Enter choice (m or d ) > d 

Are you sure you want to delete list from the glossary? 

Enter choice (y or n) > y 
list deleted from glossary. 
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Example for Changing Glossary Terms 

If you enter 2 (glossary) as the choice in the first helpadm menu, 
the following prompt will be displayed: 


Enter the name of the glossary term to be added/modi f i ed/deleted> 


If you edit the definition for shell, which is an existing term in the 
glossary, the following message will be printed: 


Editing definition for shell 


You will then be placed in the editor mode specified by the EDITOR 
export variable defined in your .profile. After you have finished 
editing the term chosen, you will be prompted with the following 
message. 


Are you satisfied with this definition (y or n)? > 


If you enter n at the prompt above, the following message will be 
displayed, and you will be placed back into the editor again. 


Re-editing definition for shell 
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After you have finished editing again, you will be prompted with the 
following message. 


Are you satisfied with this definition (y or n)? > 


If you enter y at the prompt above, the following message will be 
displayed. 


Do you want the data you have entered to be added to the 
help facility database (y or n)? > _ 


If you enter y, the changes will be entered in the database, and you 
will be returned to the shell. If you enter n, the following message 
will be displayed: 


Exiting with no changes to the help database. 


At this time you will be returned to the shell. 


Adding a term to the glossary data base is similar to changing data 
of a term. After entering a 2 in the first menu for the glossary 
option, the following prompt will be displayed: 


Enter the name of the glossary term to be added/modi f i ed/de leted> 
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You will then be placed into the editor to add the definition for the 
term. When you have finished editing, you must answer yes to the 
following prompts to have the data added to the database. 


Are you satisfied with this definition (y or n)? > _ 

Do you want the data you have entered to be added to the help 
facility database (y or n)? > _ 


When you have answered y to these prompts, the following message 
will be displayed: 


Modifications to the help glossary complete. 


ADMINISTRATION UTILITIES 


Modifying Command Information 

You must be logged in as root or bin to enter the command area of 
the Help Utilities database. If anyone else tries to change command 
data, an error message is printed at their terminal, and they will be 
returned to the shell. After you enter the command area database, 
you may add, change, or delete the following four types of 
command information: 


© Description information 
© Examples information 
© Keyword information 
• Options information. 


You will be asked to enter the name of the command whose data is 
to be added, changed, or deleted. If the command is not in the help 
database, the facility assumes that the command is to be added to 
the database. 


Note: You may only change or delete a command 
description file if you have write permission for the file. If 
you do not have write permission for the description file, an 
error message is printed at your terminal, and you will be 
returned to the shell. 


Adding Command Information 

If a command is to be added to the database, then you must enter 
information for description, example, options, and keywords when 
you are prompted. 


If you are adding description, options, or examples information, you 
will be placed in the editor specified by the EDITOR shell variable. 
You can then make the additions to the database. Adding keyword 
information will be described later. 
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When you have finished editing, you will be asked if you are satisfied 
with the screen you have changed. If you are not satisfied, you can 
re-edit the screen. When you have responded that you are satisfied 
with the screen, you will be asked if you want the changes entered 
into the database. To have the changes entered, you must respond 
by typing y for yes. If you do not type y, the database remains 
unchanged. 


You will automatically be allowed to edit the keyword list for a new 
command. There must be at least one keyword in the list before 
you will be allowed to exit the keyword list. A keyword must be a 
single word. When you have finished adding keywords, you must 
enter a period on a line by itself. You will then be asked if you are 
satisfied with the list. Once you respond to this prompt, you will be 
asked if you want the data you enter to be added to the database. 
To have the changes entered, you must respond by typing y for yes. 
If you do not type y, the database remains unchanged. This will 
complete the editing process for adding a command to the 
database. The administration facility will add the information and 
print out a message for each type of screen as the data is added for 
the new command. A message will also be displayed when all 
modifications have been done. 


Changing Command Information 

If command information is to be changed, you will be given the 
option of choosing which part is to be changed: description, option, 
examples, or keywords. When you respond, you will be placed in the 
editor specified by the EDITOR shell variable. You can then make 
the changes to the database. 


When you have finished editing, you will be asked if you are satisfied 
with the screen you have changed. If you are not satisfied, you can 
re-edit the screen. When you have responded that you are satisfied 
with the screen, you will be asked if you want the changes entered 
into the database. To have the changes entered, you must respond 
by typing y for yes. If you do not type y, the database remains 
unchanged. 
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When changing keywords in the keyword list, the list is printed on 
the terminal. Then, you are asked if you want to delete any 
keywords. If you do not want to delete any keywords, you enter a 
period on a line by itself. This will stop deletions and start additions. 
You will be prompted for a new keyword. A keyword must be a 
single word. To stop the adding process, you must enter a period 
on a line by itself. At this point, you will be given the option of 
adding more keywords or stopping. 


Deleting Command Information 

If the command already exists in the database, you will be given the 
choice of deleting the commands information when the command 
name is entered. If the command is to be deleted, all of the 
command information: description, options, examples, and keywords 
will be deleted at the same time. You must respond by typing y 
when the prompt is displayed. You will then be asked if you are sure 
you want to delete the information. The following is an example of 
removing the Is command. 


Enter the name of the command to be added/modified/deleted > Is 
The Is command is already included in help. 


Do you want to delete information on Is (y or n)? > y 

Are you sure you want to remove keywords, description, option, 

and example information for Is (y or n)? > y 

Keywords, description, option, and example information for 

Is have been deleted from the help facility database. 
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Example for Modifying Command Data 

The following is an example for adding a command to the help 
database. After you enter a 3 (command) as the choice in helpadm 
menu, the following will be displayed for adding the split command. 


Enter the name of the command to be added/modified/deleted > split 
New Command: split 

This command is not currently included in the help facility. 

You must enter a COMPLETE set of command data, including 
description and syntax information, option information, usage 
examples, and a keyword set, if ANY of the data you enter 
are to be added to the help facility’s database. You will 
be asked to explicitly request that this data be included in 
the help facility database at the end of this session. 

Editing Description Screen For split 


At this point you may add the description for the command being 
added to the database. Once the actual editing has been 
completed, the following prompt is displayed. You should then 
respond by entering a y or an n. 


Are you satisfied with this screen (y or n)? > y 
Description Screen Completed. 

Editing Options Screen for split 
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At this point you may add the options for the command being added 
to the database. Once the actual editing has been completed, the 
following prompt is displayed. You should then respond by entering 
a y or an n. 


Are you satisfied with this screen (y or n)? > y 
Options Screen Completed. 

Editing Examples Screen for split 


At this point you may add the examples for the command being 
added to the database. Once the actual editing has been 
completed, the following prompt is displayed. You should then 
respond by entering a y or an n. 


Are you satisfied with this screen (y or n)? > y 
Examples Screen Completed. 

Making Keyword List for split 

Enter a single keyword for the command after each colon (:). 
To stop adding keywords, enter a period (.). 


After entering the keywords as described and ending with a period, 
the keyword list you entered will be displayed on the terminal. The 
following prompts will be displayed after the keyword list. 


Are you satisfied with this list? (y or n) > y 
Do you want the data you have entered to be added to the help 
facility database? (y or n) > y 
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Once you enter a y to have the data entered into the database, the 
following messages will be displayed as each type screen is written 
to memory. 


Description Screen for split Updated 
Options Screen for split Updated 
Examples Screen for split Updated 
Keyword List for split Updated. 
Modifications to help database complete. 


You will now be returned to the shell from which you entered the 
helpadm command. 


The following is an example of changing data of the list command in 
the help database. After you enter a 3 (command) as the choice in 
the helpadm menu, the following will be displayed for changing the 
list command. 


Enter the name of the command to be added/modified/deleted > list 
The list command is already included in help. 

Do you want to delete information on list (y or n)? n 
Which part of the command data do you wish to edit? 

Enter d(desc), o(options), e(examp), k(keywds), or q(quit) > d 
Editing Description Screen for list 
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After editing the description of the command chosen the following 
prompt will be displayed. 


Are you satisfied with this screen (y or n)? > y 
Which part of the command data do you wish to edit? 

Enter d(desc), o(options), e(examp), k(keywds), or q(quit) > d 


You may continue editing the different parts of the command in this 
way until you are satisfied with the results. When you have finished, 
you should enter a q (quit) at the following prompt and return to the 
shell. 


Enter d(desc), o(options), e(examp), k(keywds), or q(quit) > q 


Monitoring the Use of Help 

The option of monitoring help has been provided if you want to keep 
a record of how the help facility is used. The monitor function can 
be turned off and on from the helpadm menu. Monitoring will not 
take place unless you turn on the monitor function. To set the 
option for monitoring you must enter the first helpadm menu and 
select option 5. Option 4 of the menu turns the monitor function off, 
and option 5 turns the monitor function on. After entering the 
option, you will be returned to the shell level. However, if the 
LOGNAME variable is not exported in your .profile, the monitoring 
function may not work properly. 

Setting the monitor function to record the use of help creates a file 
called HEIPIOG. A complete record of who uses the help command 
and every action taken while in the help facility is contained in this 
file. You may read this file to see the actions taken by anyone who 
uses the help facility to see such things as: which commands are 
referenced, who uses help, what mistakes are made using help, 
which module is used most, and what part of a command is 
referenced most often (options, descriptions, or examples). 
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Below is an example of the HELPLOG file: 


login*bin 

name=locate 

name=locate 

name=getkey 

name=Keysrch 

name=qui t 

login=bin 


uname=wr3b2a 
response*’ 1* 
response*’ d* 
response=’ k* 
response*’ list 
response* ’ q* 
uname=wr3b2a 


date=Mon Aug 

status=OK 

status*ERROR 

status=OK 

status=OK 

status=OK 

date=Mon Aug 


20 10:46:03 1984 


20 10:47:03 1984 


The HELPLOG file will occasionally need to be cleaned up. You can 
execute helpclean to clean out the HELPLOG file. The helpclean file 
is an executable file which removes the data in the HELPLOG file but 
does not remove the file. The data in the HELPLOG file is actually 
copied to the oHELPLOG file, and a new HELPLOG file is created. If 
you execute the helpclean command twice in succession, both the 
HELPLOG and the oHELPLOG files will be cleaned out. There are 
other ways in which you can cleanup the HELPLOG files. Some 
suggestions on other cleanup methods may be found in the Utilities 
Manual. 
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RECOMMENDATIONS FOR FORMATTING DATA 

To help users of helpadm to input data in a consistent format, the 
following guidelines are recommended. 


General Rules for All Types of Help Screens 

• Data will be presented exactly as it is entered — so, it should be 
typed the way you would like it to appear. 

© Use " \S" to cause words to be highlighted (displayed in reverse 
video) on the screen when it is displayed. The helpadm Utilities 
automatically puts the name(s) of the term highlighted into the 
buffer being edited when adding a new term. If the word is within 
the text, leave spaces before and after. For example: 

text \S word \S text 

If the word is not within text, spaces are not needed. For 
example: 

text 

\Sword\S 

text 


© The " \S" characters will not appear when the text is printed. 
Therefore, if you want words in a column to line up, you must 
account for any " \S" characters around the words. 
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Guidelines for Glossary Screens 


® A blank line at the beginning of the screen is optional. 

• Highlight the name of the term. Start typing the term in 
column 1. 

© If more than one term has the same definition and is being 
defined on the same glossary screen, then separate the 
names of the terms by a colon. For example: 

\S terml : term2 \S 

© Leave a blank line before beginning the text of a definition. 

© The text of a definition is entered in paragraph form. You 
may start in column 1 or indent. 

• Any examples in the text should be on a separate line. 

• The examples should be centered and preceded and followed 
by blank lines. For example: 

text 

example 

continuation of text 
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Guidelines for Description Screens 


© A blank line at the beginning of the screen is optional. 

• Highlight the name of the command. 

• Start typing in column 1. The helpadm Utilities automatically 
puts the name of the command highlighted into the edited buffer 
when adding a new command. 

® Leave a blank line. 

© Enter a syntax summary and an explanation of terms in the 
syntax summary, as shown: 

Syntax Summary: 


where: explanation of terms 
in syntax summary> 

When typing the words " Syntax Summary," start typing in 
column 1. 

© Leave a blank line. 

© Type " Description:" in column 1, and then skip to the next line 
and type the description of the command indented. For 
example: 

Description: 

text indented 
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Guidelines for Options Screens 

• A blank line at the beginning of the screen is optional. 

© Highlight the name of the command and the word " Options" . 
Start typing the text in column 1. For example: 

\S command-name \S: Options 

The helpadm Utilities automatically puts the name of the 
command highlighted into the screen. 

© Leave a blank line. 

• If the command has options, then type each one with an 
explanation, as shown: 

\S option \S explanation 


• If there are no options, then type the following: 
There are no options to \Scommand-name\S. 
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Guidelines for Examples Screens 


© A blank line at the beginning of the screen is optional. 

© Highlight the name of the command and the word " Examples" . 
Start typing the command in column 1. For example: 

\S command-name \S : Examples 

The helpadm Utilities automatically puts the name of the 
command highlighted into the screen. 

© Leave a blank line. 

© The example should be entered on a separate line and 
highlighted. The explanation should begin on the next line, as 
shown: 

\S command-name \S 
text of explanation 

• Each example should be separated by one blank line. 
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MANUAL PAGES 


This appendix contains the UNIX System manual pages for the Help 
Utilities. Manual pages for the following commands are provided in 
alphabetical sequence. 


help glossary starter 

helpadm locate usage 


For your convenience, the user manual pages for the Help Utilities 
are provided in both this guide and alphabetically in the 3B2 
Computer User Reference Manual. The Yellow sheet provided in this 
manual describes your options for filing the manual pages as well as 
descriptive information. 
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GLOSSARY ( i ) (Help Utilities) GLOSSARY ( 1 ) 

NAME 

glossary — definitions of common UNIX system terms and symbols 
SYNOPSIS 

[ help ] glossary [ term ] 

DESCRIPTION 

The UNIX System help Facility command glossary provides definitions of com- 
mon technical terms and symbols. 

Without an argument, glossary displays a menu screen listing the terms and 
symbols that are currently included in glossary. A user may choose one of the 
terms or may exit to the shell by typing q (for "quit"). When a term is 
selected, its definition is retrieved and displayed. By selecting the appropriate 
menu choice, the list of terms and symbols can be redisplayed. 

A term’s definition may also be requested directly from shell level (as shown 
above), causing a definition to be retrieved and the list of terms and symbols 
not to be displayed. Some of the symbols must be escaped if requested at shell 
level in order for the facility to understand the symbol. The following is a table 
which list the symbols and their escape sequence. 

SYMBOL ESCAPE SEQUENCE 

mi \"\" 

YY 

U \\[\\] 

YY 

# \# 

& \& 

* V 

\ \\\\ 

I M 

From any screen in the facility, a user may execute a command via the shell 
Cy/z(l)) by typing a ! and the command to be executed. The screen will be 
redrawn if the command that was executed was entered at a first level prompt. 
If entered at any other prompt level, only the prompt will be redrawn. 

By default, the help facility scrolls the data that is presented to the user. If a 
user prefers to have the screen clear before printing the data (non-scrolling), a 
variable must be defined in the user’s .profile file called SCROLL. The vari- 
able SCROLL must be set to no and exported for non-scrolling to occur. If the 
user later decides that scrolling is desired, the variable SCROLL must be set to 
yes or deleted form the user’s .profile file. 

Further information on the UNIX System help Facility can be found on the 
help (l), usage { 1), starter { 1), and locate { 1) manual pages. 

SEE ALSO 

help(l), locate(l), sh(l), starter(l), usage(l). 

term (5) in the 3B2 Computer System Programmer Reference Manual. 
WARNINGS 

If the TERM variable is not set in the user’s .profile file, then terminal type 
will default to the terminal value type 450 ( a hard-copy terminal ). For a list 
of valid terminal types, refer to t erm (5) inthe3B 2 Computer The help facility 
assumes that tabs are set on the user’s terminal. 
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HELP ( 1 ) 


NAME 

help — UNIX System help facility 

SYNOPSIS 

help 

[ help ] starter 

[ help ] usage [ — d ] [ — e ] [ — o ] [ commandname ] 

[ help ] locate [ keyword 1 [ keyword2 ] ... ] 

[ help ] glossary [ term ] 
help argl [ arg2 ... ] 

DESCRIPTION 

The UNIX System help facility provides on-line assistance for UNIX system 
users. 

Without arguments, help prints a menu of available on-line assistance com- 
mands with a short description of their functions. The commands and their 
descriptions are: 

COMMAND DESCRIPTION 

starter information about the UNIX system for the beginning 

user 

usage UNIX system command usage information 

locate locate UNIX system commands using function-related 

keywords 

glossary definitions of UNIX system technical terms 

The user may choose one of the above commands by entering its corresponding 
letter (given in the menu), or may exit to the shell by typing q (for "quit"). 

With arguments, help directly invokes the named on-line assistance command, 
bypassing the initial help menu. The commands starter , locate , usage , and 
glossary , optionally preceded by the word help , may also be specified at shell 
level. When executing glossary from shell level some of the symbols listed in 
the glossary must be escaped to be understood by the facility. For a list of 
symbols refer to the glossary ( 1) manual page. 

From any screen in the facility, a user may execute a command via the shell 
(j/z( 1)) by typing a ! and the command to be executed. The screen will be 
redrawn if the command that was executed was entered at a first level prompt. 
If entered at any other prompt level, only the prompt will be redrawn. 

By default, the help facility scrolls the data that is presented to the user. If a 
user prefers to have the screen clear before printing the data (non-scrolling), a 
variable must be defined in the user’s .profile file called SCROLL. The vari- 
able SCROLL must be set to no and exported for non-scrolling to occur. IF 
the user later decides that scrolling is desired, the variable SCROLL must be 
set to yes or deleted from the user’s .profile file. 

If the first argument to help is different from the four mentioned above, help 
assumes information is being requested in the form of the previous help com- 
mand (often referred to as the SCCS help command, and now obsolete). The 
arguments may be either message numbers (which normally appear in 
parentheses following messages) or command names, of one of the following 
types: 

typel Begins with non-numerics, ends in numerics. The non-numeric prefix is 
usually an abbreviation for the program or set of routines which pro- 
duced the message (e.g., ge3 for message 3 from the get command). 
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type2 Does not contain numerics (as a command, such as get). 
type3 Is all numeric (e.g., 212). 

Further information on the starter , locate , usage , and glossary commands may 
be found on the starter (1), locate (\), usage { 1), and glossary (\) manual pages, 
respectively. 

SEE ALSO 

get(l), glossary(l), locate(l), sh(l), starter(l), usage(l). 

term (5) in the 3B2 Computer System Programmer Reference Manual. 

WARNINGS 

If the TERM variable is not set in the user’s .profile file, then TERM will 
default to the terminal value type 450 ( a hard-copy terminal ). For a list of 
valid terminal types, refer to term (5). The help facility assumes that tabs are 
set on the user’s terminal. 
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HELPADM(l) 


NAME 

helpadm — make changes to the help database 

SYNOPSIS 

helpadm 

DESCRIPTION 

The UNIX System help Facility Administration command helpadm allows 
UNIX system administrators and command developers to define the content of 
help for their specific commands and to monitor use of the help facility. The 
helpadm command can only be executed by login root, login bin, or a login that 
is a member of group bin. 

The helpadm command prints a menu of 3 types of help data which can be 
modified, and 2 choices relating to monitoring use of the help facility. The five 
choices are: 

- modify startup data 

- add, modify, or delete a glossary term 

- add, modify, or delete command data (description, options, examples, and 
keywords) 

- prevent monitoring use of the help facility (login root and login bin only) 

- permit monitoring use of the help facility (login root and login bin only) 

The user may make one of the above choices by entering its corresponding 
letter (given in the menu), or may exit to the shell by typing q (for "quit"). 

If one of the first three choices is chosen, then the user is prompted for addi- 
tional information; specifically, which startup screen, glossary term definition, 
or command is to be modified. The user may also be prompted for information 
to identify whether the changes to the database are additions, modifications, or 
deletions. If the user is modifying existing data or adding new data, then they 
are prompted to make the appropriate modifications/additions. If the user is 
deleting a glossary term or a command from the database, then they must 
respond affirmatively to the next query in order for the deletion to be done. In 
any case, before the user’s changes are final, they must respond affirmatively 
when asked whether they are sure they want their requested database changes 
to be done. 

By default, helpadm will put the user into ed to make additions/modifications 
to database information. If the user wishes to be put into a different editor, 
then they should set the EDITOR variable in their environment to the desired 
editor, and then export EDITOR. 

If the user chooses to monitor/prevent monitoring use of the help facility, no 
further interaction occurs between the user and the help administration utili- 
ties. 

SEE ALSO 

ed(l), help(l). 

WARNINGS 

When the UNIX System is delivered to a customer, /etc/profile exports the 
LOGNAME variable. If /etc/profile has been changed so that LOGNAME is 
not exported, then the options to monitor/prevent monitoring use of the help 
facility may not work properly. 
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NAME 

locate — identify a UNIX system command using keywords 

SYNOPSIS 

[ help ] locate 

[ help ] locate [ keyword 1 [ keyword2 ] ... ] 

DESCRIPTION 

The locate command is part of the UNIX system help Facility, and provides 
on-line assistance with identifying UNIX system commands. 

Without arguments, the initial locate screen is displayed from which the user 
may enter keywords functionally related to the action of the desired UNIX sys- 
tem commands they wish to have identified. A user may enter keywords and 
receive a list of UNIX system commands whose functional attributes match 
those in the keyword list, or may exit to the shell by typing q (for "quit"). For 
example, if you wish to print the contents of a file, enter the keywords "print" 
and "file". The locate command would then print the names of all commands 
related to these keywords. 

Keywords may also be entered directly from the shell, as shown above. In this 
case, the initial screen is not displayed, and the resulting command list is 
printed. 

More detailed information on a command in the list produced by locate can be 
obtained by accessing the usage module of the UNIX System help Facility. 
Access is made by entering the appropriate menu choice after the command list 
is displayed. 

From any screen in the facility, a user may execute a command via the shell 
(sMl)) by typing a ! and the command to be executed. The screen will be 
redrawn if the command that was executed was entered at a first level prompt. 
If entered at any other prompt level, only the prompt will be redrawn. 

By default, the help facility scrolls the data that is presented to the user. If a 
user prefers to have the screen clear before printing the data (non-scrolling), a 
variable must be defined in the user’s .profile file called SCROLL. The vari- 
able SCROLL must be set to no and exported for non-scrolling to occur. If the 
user later decides that scrolling is desired, the variable SCROLL must be set to 
yes or deleted from the user’s .profile file. 

Further information on the UNIX System help Facility can be found on the 
helpi 1), usage (l), starter { 1), and glossary (l) manual pages. 

SEE ALSO 

glossary(l), help(l), sh(l), starter(l), usage(l). 

term (5) in the 3B2 Computer System Programmer Reference Manual. 

WARNINGS 

If the TERM variable is not set in the user’s .profile file, then TERM will 
default to the terminal value type 450 ( a hard-copy terminal ). For a list of 
valid terminal types, refer to term (5). The help facility assumes that tabs are 
set on the user’s terminal. 
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NAME 

starter — information about the UNIX system for beginning users 

SYNOPSIS 

[ help ] starter 

DESCRIPTION 

The UNIX System help Facility command starter provides five categories of 
information about the UNIX system to assist new users. 

The five categories are: 

- commands a new user should learn first 

- UNIX system documents important for beginners 

- education centers offering UNIX system courses 

- local environment information 

- on-line teaching aids installed on the UNIX system 

The user may choose one of the above categories by entering its corresponding 
letter (given in the menu), or may exit to the shell by typing q (for "quit"). 
When a category is chosen, the user will receive one or more pages of informa- 
tion pertaining to it. 

From any screen in the facility, a user may execute a command via the shell 
Cs7z(l)) by typing a ! and the command to be executed. The screen will be 
redrawn if the command that was executed was entered at a first level prompt. 
If entered at any other prompt level, only the prompt will be redrawn. 

By default, the help facility scrolls the data that is presented to the user. If a 
user prefers to have the screen cleared before printing the data (non-scrolling), 
a variable must be defined in the user’s .profile file called SCROLL. The vari- 
able SCROLL must be set to no and exported for non-scrolling to occur. If the 
user later decides that scrolling is desired, the variable SCROLL must be set to 
yes or deleted from the user’s .profile file. 

Further information on the UNIX System help Facility can be found on the 
helpi 1), usage { 1), locate (l), and glossary { 1) manual pages. 

SEE ALSO 

glossary(l), help(l), locate(l), sh(l), usage(l). 

term (5) in the 3B2 Computer System Programmer Reference Manual. 

WARNINGS 

If the TERM variable is not set in the user’s .profile file, then TERM will 
default to the terminal value type 450 ( a hard-copy terminal ). For a list of 
valid terminal types, refer to term (5). The help facility assumes that tabs are 
set on the user’s terminal. 
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NAME 

usage — retrieve a command description and usage examples 
SYNOPSIS 

[ help ] usage [ — d ] [ — e ] [ — o ] [ command_name ] 

DESCRIPTION 

The UNIX System help Facility command usage retrieves information about 
UNIX system commands. With no argument, usage displays a menu screen 
prompting the user for the name of a command, or allows the user to retrieve a 
list of commands supported by usage. The user may also exit to the shell by 
typing q (for "quit). 

After a command is selected, the user is asked to choose among a description of 
the command, examples of typical usage of the command, or descriptions of the 
command’s options. Then, based on the user’s request, the appropriate infor- 
mation will be printed. 

A command name may also be entered at shell level as an argument to usage. 
To receive information on the command’s description, examples, or options, the 
user may use the — d, — e, or — o options respectively. (The default option is 

-d.) 

From any screen in the facility, a user may execute a command via the shell 
(5/2(1)) by typing a ! and the command to be executed. The screen will be 
redrawn if the command that was executed was entered at a first level prompt. 
If entered at any other prompt level, only the prompt will be redrawn. 

By default, the help facility scrolls the data that is presented to the user. If a 
user prefers to have the screen cleared before printing the data (non-scrolling), 
a variable must be defined in the user’s .profile file called SCROLL. The vari- 
able SCROLL must be set to no and exported for non-scrolling to occur. If the 
user later decides that scrolling is desired, the variable SCROLL must be set to 
yes or deleted from the user’s .profile file. 

Further information on the UNIX System help Facility can be found on the 
help( 1), located 1), starter ( 1), and glossary { 1) manual pages. 

SEE ALSO 

glossary(l), help(l), locate(l), sh(l), starter(l). 

term (5) in the 3B2 Computer System Programmer Reference Manual. 

WARNINGS 

If the TERM variable is not set in the user’s .profile file, then TERM will 
default to the terminal value type 450 ( a hard-copy terminal ). For a list of 
valid terminal types, refer to term(5). The help facility assumes that tabs are 
set on the user’s terminal. 


10/84 


- 1 - 


10/84 




Index 


A 

Adding Command Information 7-12 

Administration Utilities 7-1 

B 

Bypassing the Help Menu 2-7 

c 

Changing Glossary Information 7-7 

Changing Starter Information 7-3 

D 

Display Conventions 1-2 

E 

Entering Glossary Screen 1 (Terms) 4-2 

Entering Glossary Screen 2 (Definitions) 4-4 

Entering Locate Screen 1 5-2 

Entering Locate Screen 2 5-2 

Entering Starter Command Screen 3-3 

Entering Starter Documents Screen 3-5 

Entering Starter Education Screen 3-5 

Entering Starter Local Screen 3-6 

Page 1 




INDEX 


Entering Starter Screen 1 3-2 

Entering Starter Teach Screen 3-8 

Entering the Help Menu 2-5 

Entering Usage Description Screen 6-4 

Entering Usage Example Screen 6-5 

Entering Usage List Screen 6-3 

Entering Usage Options Screen 6-7 

Entering Usage Screen 1 6-2 

error messages 2-7 

Example for Changing Glossary Terms 7-9 

Example for Modifying Command Data 7-15 

Example of Changing Starter Data 7-4 

F 

feature highlights 1-2 

G 

General Rules for Formatting Help Screens 7-20 

Glossary Module 4-1 

Glossary Screen 1 Options 4-3 

Glossary Screen 2 Options 4-4 

Glossary Screens 4-1 

Guide Organization 1-3 

Guidelines for Description Screens 7-22 

Guidelines for Examples Screens 7-24 

Guidelines for Glossary Screens 7-21 

Guidelines for Options Screens 7-23 

H 

Help Menu 2-3 

Help Menu, Options 2-6 

help menu, screen 1 2-5 

Help Screen 1 2-1 

helpadm Menu 7-2 


Page 2 



INDEX 


I 

illegal characters 2-7 

L 

locate example 5-4 

Locate Module 5-1 

Locate Screen 1 Options 5-2 

Locate Screen 2 Options 5-3 

Locate Screens 5-1 

Lower Level Modules 2-8 

M 

Modifying Command Information 7-12 

Module Contents 2-8 

Monitoring the Use of Help 7-18 

R 

Recommendations for Formatting Data 7-20 

s 

SCROLL variable 2-3 

Setting Up Your Terminal 2-2 

Starter Module 3-1 

Starter Screens 3-2 

T 

TERM variable 2-2 


Page 3 




INDEX 


u 

Usage Contents Screens 6-2 

Usage Description Screen Example 6-12 

Usage Description Screen Options 6-5 

Usage Example Screen Options 6-6 

Usage Examples Screen Example 6-13 

Usage List Screen Example 6-10 

Usage List Screen Options 6-4 

Usage Module 6-1 

usage module examples 6-9 

Usage Options Screen Example 6-14 

Usage Options Screen Options 6-8 

Usage Screen 1 Example 6-9 

Usage Screen 1 Options 6-3 


Page 4 



